
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMAKE_GENERATOR_INSTANCE &mdash; CMake 3.27.4 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />
    
    <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/sphinx_highlight.js"></script>
    
    <link rel="shortcut icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMAKE_GENERATOR_PLATFORM" href="CMAKE_GENERATOR_PLATFORM.html" />
    <link rel="prev" title="CMAKE_GENERATOR" href="CMAKE_GENERATOR.html" />
 

  </head><body>

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="CMAKE_GENERATOR_PLATFORM.html" title="CMAKE_GENERATOR_PLATFORM"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="CMAKE_GENERATOR.html" title="CMAKE_GENERATOR"
             accesskey="P">previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.27.4 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-variables.7.html" accesskey="U">cmake-variables(7)</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">CMAKE_GENERATOR_INSTANCE</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="cmake-generator-instance">
<span id="variable:CMAKE_GENERATOR_INSTANCE"></span><h1>CMAKE_GENERATOR_INSTANCE<a class="headerlink" href="#cmake-generator-instance" title="Permalink to this heading">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.11.</span></p>
</div>
<p>Generator-specific instance specification provided by user.</p>
<p>Some CMake generators support selection of an instance of the native build
system when multiple instances are available.  If the user specifies an
instance (e.g. by setting this cache entry or via the
<span class="target" id="index-0-envvar:CMAKE_GENERATOR_INSTANCE"></span><a class="reference internal" href="../envvar/CMAKE_GENERATOR_INSTANCE.html#envvar:CMAKE_GENERATOR_INSTANCE" title="CMAKE_GENERATOR_INSTANCE"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">CMAKE_GENERATOR_INSTANCE</span></code></a> environment variable), or after a default
instance is chosen when a build tree is first configured, the value will be
available in this variable.</p>
<p>The value of this variable should never be modified by project code.
A toolchain file specified by the <span class="target" id="index-0-variable:CMAKE_TOOLCHAIN_FILE"></span><a class="reference internal" href="CMAKE_TOOLCHAIN_FILE.html#variable:CMAKE_TOOLCHAIN_FILE" title="CMAKE_TOOLCHAIN_FILE"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_TOOLCHAIN_FILE</span></code></a>
variable may initialize <code class="docutils literal notranslate"><span class="pre">CMAKE_GENERATOR_INSTANCE</span></code> as a cache entry.
Once a given build tree has been initialized with a particular value
for this variable, changing the value has undefined behavior.</p>
<p>Instance specification is supported only on specific generators.</p>
<section id="visual-studio-instance-selection">
<h2>Visual Studio Instance Selection<a class="headerlink" href="#visual-studio-instance-selection" title="Permalink to this heading">¶</a></h2>
<p><a class="reference internal" href="../manual/cmake-generators.7.html#visual-studio-generators"><span class="std std-ref">Visual Studio Generators</span></a> support instance specification for
Visual Studio 2017 and above.  The <code class="docutils literal notranslate"><span class="pre">CMAKE_GENERATOR_INSTANCE</span></code> variable
may be set as a cache entry selecting an instance of Visual Studio
via one of the following forms:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">location</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">location[,key=value]*</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">key=value[,key=value]*</span></code></p></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">location</span></code> specifies the absolute path to the top-level directory
of the VS installation.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">key=value</span></code> pairs form a comma-separated list of options to
specify details of the instance selection.
Supported pairs are:</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">version=&lt;major&gt;.&lt;minor&gt;.&lt;date&gt;.&lt;build&gt;</span></code></dt><dd><div class="versionadded">
<p><span class="versionmodified added">New in version 3.23.</span></p>
</div>
<p>Specify the 4-component VS Build Version, a.k.a. Build Number.</p>
<p>The components are:</p>
<p><code class="docutils literal notranslate"><span class="pre">&lt;major&gt;.&lt;minor&gt;</span></code></p>
<blockquote>
<div><p>The VS major and minor version numbers.
These are the same as the release version numbers.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">&lt;date&gt;</span></code></p>
<blockquote>
<div><p>A build date in the format <code class="docutils literal notranslate"><span class="pre">MMMDD</span></code>, where <code class="docutils literal notranslate"><span class="pre">MMM</span></code> is a month index
since an epoch used by Microsoft, and <code class="docutils literal notranslate"><span class="pre">DD</span></code> is a day in that month.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">&lt;build&gt;</span></code></p>
<blockquote>
<div><p>A build index on the day represented by <code class="docutils literal notranslate"><span class="pre">&lt;date&gt;</span></code>.</p>
</div></blockquote>
<p>The build number is reported by <code class="docutils literal notranslate"><span class="pre">vswhere</span></code> as <code class="docutils literal notranslate"><span class="pre">installationVersion</span></code>.
For example, VS 16.11.10 has build number <code class="docutils literal notranslate"><span class="pre">16.11.32126.315</span></code>.</p>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.23: </span>A portable VS instance, which is not known to the Visual Studio Installer,
may be specified by providing both <code class="docutils literal notranslate"><span class="pre">location</span></code> and <code class="docutils literal notranslate"><span class="pre">version=</span></code>.</p>
</div>
<p>If the value of <code class="docutils literal notranslate"><span class="pre">CMAKE_GENERATOR_INSTANCE</span></code> is not specified explicitly
by the user or a toolchain file, CMake queries the Visual Studio Installer
to locate VS instances, chooses one, and sets the variable as a cache entry
to hold the value persistently.  If an environment variable of the form
<code class="docutils literal notranslate"><span class="pre">VS##0COMNTOOLS</span></code>, where <code class="docutils literal notranslate"><span class="pre">##</span></code> the Visual Studio major version number,
is set and points to the <code class="docutils literal notranslate"><span class="pre">Common7/Tools</span></code> directory within one of the
VS instances, that instance will be used.  Otherwise, if more than one
VS instance is installed we do not define which one is chosen by default.</p>
<p>The VS version build number of the selected VS instance is provided in
the <span class="target" id="index-0-variable:CMAKE_VS_VERSION_BUILD_NUMBER"></span><a class="reference internal" href="CMAKE_VS_VERSION_BUILD_NUMBER.html#variable:CMAKE_VS_VERSION_BUILD_NUMBER" title="CMAKE_VS_VERSION_BUILD_NUMBER"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_VS_VERSION_BUILD_NUMBER</span></code></a> variable.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">CMAKE_GENERATOR_INSTANCE</a><ul>
<li><a class="reference internal" href="#visual-studio-instance-selection">Visual Studio Instance Selection</a></li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="CMAKE_GENERATOR.html"
                          title="previous chapter">CMAKE_GENERATOR</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="CMAKE_GENERATOR_PLATFORM.html"
                          title="next chapter">CMAKE_GENERATOR_PLATFORM</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/variable/CMAKE_GENERATOR_INSTANCE.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="CMAKE_GENERATOR_PLATFORM.html" title="CMAKE_GENERATOR_PLATFORM"
             >next</a> |</li>
        <li class="right" >
          <a href="CMAKE_GENERATOR.html" title="CMAKE_GENERATOR"
             >previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.27.4 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-variables.7.html" >cmake-variables(7)</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">CMAKE_GENERATOR_INSTANCE</a></li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
        &#169; Copyright 2000-2023 Kitware, Inc. and Contributors.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>